Skip to content

feat(docs): add custom badge generator#2152

Merged
ghostdevv merged 22 commits intonpmx-dev:mainfrom
trueberryless:feature/docs-custom-badges-inputs
Mar 21, 2026
Merged

feat(docs): add custom badge generator#2152
ghostdevv merged 22 commits intonpmx-dev:mainfrom
trueberryless:feature/docs-custom-badges-inputs

Conversation

@trueberryless
Copy link
Contributor

@trueberryless trueberryless commented Mar 19, 2026

🧭 Context

In the last npmx meetup, we were discussing the idea of adding a generator inside the docs for custom badges to simplify the process of getting the Markdown content.

So I played around with the idea a little bit and landed on this implementation, which I find pretty useful.

📚 Description

I moved the custom badges docs to their dedicated page because they are like 50% of the features page and I think since there are many subheadings, it makes sense to be able to see them in the ToC (therefore the dedicated page).

And then I created a little BadgeGenerator.vue which let's the user input the package name and the type of info they wanna have in the badge with a little preview.

Feel free to suggest reverts or further ideas for this improvement.

I also played around a bit with updating the package in the ## Examples section dynamically to what the user currently has typed in the input, but I couldn't figure out a clean way to create the code block like this with a component, which sucks a little bit. Therefore, I dropped this, but if you know how we could do that, feel free to guide me to a possible solution.

Here is a deployment preview of the right page: https://docsnpmxdev-git-fork-trueberryless-feature-docs-cus-74ef86-npmx.vercel.app/guide/badges

@vercel
Copy link

vercel bot commented Mar 19, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
npmx.dev Ready Ready Preview, Comment Mar 21, 2026 3:33pm
2 Skipped Deployments
Project Deployment Actions Updated (UTC)
docs.npmx.dev Ignored Ignored Preview Mar 21, 2026 3:33pm
npmx-lunaria Ignored Ignored Mar 21, 2026 3:33pm

Request Review

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Mar 19, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds two new Nuxt/Vue components (docs/app/components/BadgeGenerator.vue and docs/app/components/BadgeGeneratorParameters.vue) that provide interactive badge previews, validation, query-parameter configuration, and clipboard-copying of npmx badge Markdown/URLs. Removes the "Custom badges" section from docs/content/2.guide/1.features.md and adds a new badges documentation page at docs/content/2.guide/6.badges.md enumerating supported badge types, examples, scoped/version handling and query-parameter options. Extends server/api/registry/badge/[type]/[...pkg].get.ts with a new name badge strategy.

Possibly related PRs

Suggested labels

documentation

Suggested reviewers

  • danielroe
🚥 Pre-merge checks | ✅ 1
✅ Passed checks (1 passed)
Check name Status Explanation
Description check ✅ Passed The pull request description clearly relates to the changeset, explaining the context from a meetup discussion, the decision to move badges documentation to a dedicated page, and the implementation of an interactive BadgeGenerator component with live preview functionality.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
docs/app/components/BadgeGenerator.vue (1)

1-1: Add TypeScript to the script block.

The coding guidelines require following TypeScript conventions for .vue files. Adding lang="ts" enables type checking and improves maintainability.

♻️ Suggested change
-<script setup>
+<script setup lang="ts">

As per coding guidelines: **/*.{ts,tsx,vue}: Follow standard TypeScript conventions and best practices.


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 3a4b4df4-d9c9-4836-b881-79fedefbb8f3

📥 Commits

Reviewing files that changed from the base of the PR and between 230b7c7 and 89d5ebf.

📒 Files selected for processing (3)
  • docs/app/components/BadgeGenerator.vue
  • docs/content/2.guide/1.features.md
  • docs/content/2.guide/6.badges.md
💤 Files with no reviewable changes (1)
  • docs/content/2.guide/1.features.md

@codecov
Copy link

codecov bot commented Mar 19, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

@graphieros
Copy link
Contributor

What do you think of having the option to create a custom badge ? Any label, any value

@trueberryless
Copy link
Contributor Author

What do you think of having the option to create a custom badge ? Any label, any value

Since the existing parameters allow for that, I would say we could create a second component for the parameter section, which allows to set all the parameters. But I didn't wanted to overload the start of the page with such an overwhelming component. Awesome idea, gonna work on it 👍

@jycouet
Copy link
Contributor

jycouet commented Mar 19, 2026

What do you think of having the option to create a custom badge ? Any label, any value

Since the existing parameters allow for that, I would say we could create a second component for the parameter section, which allows to set all the parameters. But I didn't wanted to overload the start of the page with such an overwhelming component. Awesome idea, gonna work on it 👍

You can say that you want 2 contributions it's ok 😅


Awesome work @trueberryless IRL meetups are everything ^^

@trueberryless
Copy link
Contributor Author

You can say that you want 2 contributions it's ok 😅

Actually, I want to do the addition of the second component in this PR as well, to ship this feature as one single unit. That way it feels cohesive.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (3)
docs/app/components/BadgeGenerator.vue (1)

1-5: Consider adding TypeScript for type safety.

The <script setup> block lacks lang="ts". Adding TypeScript would provide better type safety for the reactive state and function signatures, aligning with the coding guidelines for .vue files.

-<script setup>
+<script setup lang="ts">
 const pkg = useState('badge-pkg', () => 'nuxt')
 const type = useState('badge-type', () => 'version')
-const isValid = ref(true)
-const copied = ref(false)
+const isValid = ref<boolean>(true)
+const copied = ref<boolean>(false)
docs/app/components/BadgeGeneratorParameters.vue (2)

1-11: Consider adding TypeScript and reducing duplication with BadgeGenerator.vue.

Both components share the same types array, copyToClipboard pattern, and state keys (badge-pkg, badge-type). Consider:

  1. Adding lang="ts" for type safety
  2. Extracting shared constants/utilities to a composable or shared module
-<script setup>
+<script setup lang="ts">
+// Consider extracting to a shared composable:
+// import { useBadgeGenerator, BADGE_TYPES } from '~/composables/useBadgeGenerator'

234-243: Consider adding an accessible label for the toggle.

The checkbox toggle for "Use package name as label" uses sr-only for the input but lacks an id/for association or aria-label. Screen reader users may have difficulty understanding the toggle's purpose.

♿ Suggested improvement
-      <label class="relative inline-flex items-center cursor-pointer group">
-        <input v-model="usePkgName" type="checkbox" class="sr-only peer" />
+      <label for="use-pkg-name-toggle" class="relative inline-flex items-center cursor-pointer group">
+        <input id="use-pkg-name-toggle" v-model="usePkgName" type="checkbox" class="sr-only peer" />

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 575c0ad8-dd7a-44a1-a52a-64b70354146a

📥 Commits

Reviewing files that changed from the base of the PR and between 3907e95 and 381114c.

📒 Files selected for processing (3)
  • docs/app/components/BadgeGenerator.vue
  • docs/app/components/BadgeGeneratorParameters.vue
  • docs/content/2.guide/6.badges.md

@trueberryless
Copy link
Contributor Author

I'm gonna work on the "any value" part tomorrow, as this is actually not currently supported by the API, so I'll have to add it 👍

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (2)
docs/app/components/BadgeGeneratorParameters.vue (1)

132-134: Consider using colon syntax for UnoCSS icons.

The icons use dash-separated syntax (i-lucide-chevron-down, i-lucide-alert-circle). Per project conventions, colon syntax aids UnoCSS in resolving the correct collection directly.

♻️ Suggested changes
-            class="absolute right-3 top-1/2 -translate-y-1/2 i-lucide-chevron-down w-4 h-4 text-gray-400 pointer-events-none"
+            class="absolute right-3 top-1/2 -translate-y-1/2 i-lucide:chevron-down w-4 h-4 text-gray-400 pointer-events-none"
-            class="i-lucide-alert-circle w-3.5 h-3.5 text-red-500 ml-1"
+            class="i-lucide:alert-circle w-3.5 h-3.5 text-red-500 ml-1"

Apply the same pattern at line 238.

Based on learnings: "In Vue components that use UnoCSS with the preset-icons collection, prefer colon-syntax for icons (e.g., i-carbon:checkmark) over the dash-separated form."

Also applies to: 212-215, 236-239

docs/app/components/BadgeGenerator.vue (1)

88-90: Consider colon syntax for UnoCSS icon.

♻️ Suggested change
-          class="absolute right-3 top-1/2 -translate-y-1/2 i-lucide-chevron-down w-4 h-4 text-gray-400 pointer-events-none"
+          class="absolute right-3 top-1/2 -translate-y-1/2 i-lucide:chevron-down w-4 h-4 text-gray-400 pointer-events-none"

Based on learnings: "prefer colon-syntax for icons (e.g., i-carbon:checkmark) over the dash-separated form."


ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ed02db5e-0e3a-45e0-b5d6-112db2b729a9

📥 Commits

Reviewing files that changed from the base of the PR and between 381114c and 2d41b40.

📒 Files selected for processing (2)
  • docs/app/components/BadgeGenerator.vue
  • docs/app/components/BadgeGeneratorParameters.vue

@graphieros
Copy link
Contributor

graphieros commented Mar 19, 2026

In the list, I would recommend to position the colour badges at the start of the lines, so they are all nicely aligned. Wdyt ?

@trueberryless
Copy link
Contributor Author

In the list, I would recommend to position the colour badges at the start of the lines, so they are all nicely aligned. Wdyt ?

You mean these badges here at the end to the front?

image

I'm not totally sure if this would make it cleaner. First, some have two colors depending on the value, like vulnerabilities or types. Second, this would make the actual type not aligned, and the boldness of it wouldnt be as noticeable. I personally think that the colour badges should be a subtle addition at the end.

@ghostdevv
Copy link
Contributor

After some sleep I'll figure out why I broke knip and we can merge this!

@ghostdevv ghostdevv force-pushed the feature/docs-custom-badges-inputs branch from 79cf265 to a588ac1 Compare March 21, 2026 15:30
@ghostdevv ghostdevv marked this pull request as ready for review March 21, 2026 15:32
@ghostdevv ghostdevv enabled auto-merge March 21, 2026 15:33
@ghostdevv ghostdevv added this pull request to the merge queue Mar 21, 2026
@ghostdevv
Copy link
Contributor

This reminds me actually that @yuyinws made a badge builder website - if there is anything missing from this impl we could add it in a follow up 👀

@trueberryless
Copy link
Contributor Author

We could add a link to it for more complex generations in another PR 🙌

Merged via the queue into npmx-dev:main with commit 2501b3c Mar 21, 2026
19 checks passed
@github-actions github-actions bot mentioned this pull request Mar 21, 2026
@trueberryless trueberryless deleted the feature/docs-custom-badges-inputs branch March 21, 2026 19:55
@coderabbitai coderabbitai bot mentioned this pull request Mar 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants